Skip to content

fix: Twist2.ad raised ValueError for every twist; add Twist2.Ad and SE2.Ad - #259

Merged
taughz merged 1 commit into
rai-opensource:masterfrom
petercorke:fix/twist2-ad
Oct 26, 2026
Merged

taughz merged 1 commit into
rai-opensource:masterfrom
petercorke:fix/twist2-ad

Conversation

@petercorke

Copy link
Copy Markdown
Collaborator

Problem

Twist2.ad raises ValueError: argument must be a 1- or 3-vector for every twist, and always has. It is a copy of Twist3.ad that was never adapted to 2D: it calls skew() on the scalar w and builds 6x6 blocks, where the 2D result is 3x3. Nothing in the repo calls it and no test covered it.

It also differs from its 3D sibling in other ways:

  • It is a @property, while Twist3.ad is a method and both docstrings say S.ad().
  • Its docstring example calls S.unit(), and its see-also points at SE3.Ad.
  • Twist2 has no Ad(), and neither does SE2. tr2adjoint2 exists, but only as a base function, so the ad/Ad pair that Twist3 and SE3 have was half missing in 2D.

Changes

  • Twist2.ad() is now a method returning the 3x3 matrix of the Lie bracket, [[0, -ω, v_y], [ω, 0, -v_x], [0, 0, 0]]. For a sequence it returns a list, as skewa() does.
  • Twist2.Ad() is new and mirrors Twist3.Ad(): the adjoint of the equivalent SE(2) pose.
  • SE2.Ad() is new and mirrors SE3.Ad().
  • tr2adjoint2 docstring: its text named tr2jac2 and said 6x6. Now it names tr2adjoint2 and gives 3x3 (1x1 for SO(2)).

Verification

The new tests/test_twist2_adjoint.py checks against independent oracles, not against the implementation:

  • ad(S) @ T equals the commutator of the augmented skew matrices, vee([S, T]).
  • Antisymmetry: [S, S] = 0 and ad(S) T = -ad(T) S.
  • expm(ad(S)) equals Ad(exp(S)).
  • SE2.Ad() @ S equals vee(T [S] T^-1).
  • Ad(T1 T2) = Ad(T1) Ad(T2), and Ad of the identity is I.
  • Sequence handling.

All six fail on master and pass here. Full suite: 386 passed, 3 skipped. Black is clean. The branch merges cleanly with #225, #248, #249, #258 and the integration hub #246.

Not changed

  • tr2adjoint and tr2adjoint2 both have a .. math: directive with a single colon (so it renders as a comment) and unbalanced braces in the formula. I left those alone because the 3D function shares them and fixing the math needs a check of the Sphinx macros.
  • Twist3.ad() silently uses the first element of a sequence. Twist2.ad() returns a list, so the two now differ for sequences. I'd harmonize them separately.

🤖 Generated with Claude Code

…E2.Ad

Twist2.ad was a copy of Twist3.ad that was never adapted to 2D: it called
skew() on the scalar w and built 6x6 blocks, so it raised ValueError for any
Twist2. It was also a property while Twist3.ad is a method, and its
docstring example called unit().

Rewrite it as a method returning the 3x3 matrix of the Lie bracket,

    [[0, -w, vy], [w, 0, -vx], [0, 0, 0]]

and return a list for a sequence, as skewa() does. Add Twist2.Ad() and
SE2.Ad() (tr2adjoint2 existed but only as a base function) to match
Twist3.Ad and SE3.Ad.

Also correct the 2D-specific text in tr2adjoint2's docstring, which named
tr2jac2 and said 6x6.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@petercorke
petercorke requested a review from taughz as a code owner October 15, 2026 00:39
@codecov-commenter

Copy link
Copy Markdown

⚠️ Please install the 'codecov app svg image' to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@taughz
taughz merged commit 13cef32 into rai-opensource:master Oct 26, 2026
13 checks passed
taughz pushed a commit that referenced this pull request Oct 26, 2026
…#260)

## Problem

The math block in the `tr2adjoint` and `tr2adjoint2` docstrings has
never rendered, and would not have rendered correctly if it had:

```rst
.. math:

    Ad(\mat{T}) \vec{X} X = \vee \left( \mat{T} \skew{\vec{X} \mat{T}^{-1} \right)
```

- **Single colon:** `.. math:` is not the directive (`.. math::` is).
reST treats it as a comment, so the whole block was swallowed and
nothing showed in the docs.
- **Undefined macro:** `\skew` is not defined in `docs/source/conf.py`.
The macros there are `\sk`, `\skx` and `\vex`.
- **Unbalanced braces:** `\skew{...` was never closed.
- **Stray `X`:** there is an extra trailing `X`, and `Ad` was set in
italic, so it read as `A·d`.

The inline `\mat{T} \in \SE3` below it only worked because `\SE` takes
one argument, so `\SE3` parses as `\SE` applied to `3`. The docs
elsewhere write `\SE{3}`.

The 2D docstring was a copy of the 3D one, so both carried the same
errors. The 3D text also named `tr2jac` and gave only the 6x6 size.

## Change

- The block is now `.. math::` with `\mathrm{Ad}(\mat{T})\,\vec{X} =
\vex{\mat{T}\,\sk{\vec{X}}\,\mat{T}^{-1}}`, written with the macros
already defined in `conf.py`. No change to `conf.py` was needed.
- `\SE3` and `\SE2` are now `\SE{3}` and `\SE{2}`.
- The 3D text names `tr2adjoint` and gives 6x6 for SE(3), 3x3 for SO(3).

Docstrings only, so no behavior change.

## Verification

- Parsing each docstring with docutils: math-block nodes went from 0 to
1 for both functions.
- Every macro in the formula is defined in `conf.py`, and the braces
balance.
- Searched the package for other single-colon `.. math:` directives and
for `\skew`, `\SE3` or `\SO3`; none remain.
- Full suite: 380 passed, 3 skipped.
- Merge simulations against #225, #246, #248, #249, #258 and #259 are
all clean. This PR and #259 both edit the `tr2adjoint2` docstring, but
in separate hunks.

**Not verified:** I have not looked at it rendered in a browser. MathJax
runs client-side, so a docs build would show only the raw TeX. A quick
look at the built page before merging would be worthwhile.

Related: #259, which fixed the other 2D-specific text in `tr2adjoint2`.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants